.\" $Id: PAPI_overflow.3,v 1.16 2004/10/01 18:44:06 terpstra Exp $
.TH PAPI_overflow 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
 PAPI_overflow \- set up an event set to begin registering overflows
 _papi_overflow_handler \- user defined function to process overflow events

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_overflow 
.BI "      (int " EventSet ", int " EventCode ", int " threshold ", int " flags ", PAPI_overflow_handler_t " handler ");"
.BI "(*PAPI_overflow_handler_t)\ _papi_overflow_handler 
.BI "      (int " EventSet ", void * " address ", long_long " overflow_vector ", void * " context ");"
.fi
.B Fortran Interface
.nf
.I Not implemented
.fi

.SH DESCRIPTION
.B PAPI_overflow()
marks a specific 
.I EventCode 
in an 
.I EventSet 
to generate an overflow signal after every 
.I threshold
events are counted. More than one event in an event set can be used to trigger 
overflows. In such cases, the user must call this function once 
for each overflowing event. To turn off overflow on a specified event, 
call this function with a 
.I threshold 
value of 0.
.LP
Overflows can be implemented in either software or hardware, but the
scope is the entire event set. PAPI defaults to hardware overflow if it is available.
In the case of software overflow, a periodic timer
interrupt causes PAPI to compare the event counts against the 
.I threshold 
values and call the overflow handler if one or more events have exceeded their
.I threshold.
In the case of hardware overflow, the counters are typically set to the negative of the
.I threshold 
value and count up to 0. This zero-crossing triggers a hardware interrupt
that calls the overflow handler. Because of this counter interrupt, the counter values 
for overflowing counters may be very small or even negative numbers, and cannot be relied upon
as accurate. In such cases the overflow handler can approximate the counts by supplying the
.I threshold
value whenever an overflow occurs.
.LP
.B _papi_overflow_handler()
is a placeholder for a user-defined function to process overflow events. 
A pointer to this function is passed to the
.B PAPI_overflow 
routine, where it is invoked whenever a software or hardware overflow occurs.
This handler receives the 
.I EventSet
of the overflowing event, the Program Counter 
.I address 
when the interrupt occured, an
.I overflow_vector
that can be processed to determined which event(s) caused the overflow, 
and a pointer to the machine 
.I context, 
which can be used in a platform-specific manor
to extract register information about what was happening when the overflow occured.

.SH ARGUMENTS
.I EventSet 
--  an integer handle to a PAPI event set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I EventCode 
-- the preset or native event code to be set for overflow detection. 
This event must have already been added to the
.I EvenSet.
.LP
.I threshold 
-- the overflow threshold value for this
.I EventCode.
.LP
.I flags 
-- bit map that controls the overflow mode of operation. Set to PAPI_OVERFLOW_FORCE_SW
to force software overflowing, even if hardware overflow support is available.
If hardware overflow support is available on a given system, 
it will be the default mode of operation. There are situations where it
is advantageous to use software overflow instead. Although software overflow
is inherently less accurate, with more latency and processing overhead, it does
allow for overflowing on derived events, and for the accurate recording of
overflowing event counts. These two features are typically not available with 
hardware overflow. Only one type of overflow is allowed 
per event set, so setting one event to hardware overflow and another to 
forced software overflow will result in an error being returned.
.LP
.I handler 
-- pointer to the user supplied handler function to call upon overflow
.LP
.I address 
-- the Program Counter address at the time of the overflow
.LP
.I overflow_vector 
-- a long_long word containing flag bits to indicate which hardware counter(s) caused the overflow
.LP
.I *context 
-- pointer to a machine specific structure that defines the register context at the time of overflow.
This parameter is often unused and can be ignored in the user function.
.LP

.SH RETURN VALUES
On success, 
.B PAPI_overflow 
returns
.B "PAPI_OK."
On error, a non-zero error code is returned.
.B _papi_overflow_handler
is a void function and returns nothing.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
Specifically, a bad threshold value.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.
.TP
.B "PAPI_EISRUN"
The EventSet is currently counting events.
.TP
.B "PAPI_ECNFLCT"
The underlying counter hardware cannot count this event and other events
in the EventSet simultaneously. Or you are trying to overflow both by
hardware and by forced software at the same time.
.TP
.B "PAPI_ENOEVNT"
The PAPI preset is not available on the underlying hardware. 

.SH EXAMPLES
Define a simple overflow handler:
.nf
.if t .ft CW
void handler(int EventSet, void *address, long_long overflow_vector, void *context)
{
  fprintf(stderr,"Overflow at %p! bit=0x%llx \en",
	  address,overflow_vector);
}
.if t .ft P
.fi

Call PAPI_overflow for an event set containing the PAPI_TOT_INS event,
setting the threshold to 100000. Use the handler defined above.
.nf
.if t .ft CW
  retval = PAPI_overflow(EventSet, PAPI_TOT_INS, 100000, 0, handler);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_get_overflow_event_index "(3)"
